home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 701-725 / 714 / xstat / xstat.doc < prev    next >
Text File  |  1995-03-18  |  12KB  |  398 lines
  1. XStat V1.07 Documentation
  2. =========================
  3.  
  4. IMPORT StdDisclaimer; (* in short: use it at your own risk *)
  5. XStat was carefully tested, but there's certainly plenty of room for bugs.
  6.  
  7. XStat V1.07 is Freeware, non-commercial distribution is o.k. as long as
  8. the following conditions are met:
  9.  
  10.   * Source, executable and documentation must be distributed together
  11.     (XStat.mod, XStat, XStat.data, XStat.doc, XStat.dok and Make),
  12.     and these files must be intact (you're not allowed to make changes).
  13.  
  14.   * Disk librarians: you may charge no more than the current price
  15.     of a single AmigaLibDisk from Fred Fish
  16.  
  17.  
  18.  
  19. XStat requires AmigaOS V37 or later (that's 2.04 or later).
  20.  
  21.  
  22.  
  23. Purpose
  24. =======
  25. XStat extracts statistic information from the Xferstat file created
  26. by Andrew "Charly" Kopp's UUCiCo V1.15c (or later). The most important
  27. information XStat offers to you is the phone cost for a certain number
  28. of connects.
  29.  
  30.  
  31.  
  32. Installation
  33. ============
  34. Copy the executable "XStat" to a dircetory in your "Path", preferably UUBIN:
  35.  
  36. There's only one more file that needs to be installed; it's called
  37. "XStat.data", and should be copied to your UULIB: directory.
  38.  
  39. You'll have to edit XStat.data to complete the installation.
  40.  
  41.  
  42.  
  43. XStat.data
  44. ==========
  45. XStat.data contains the phone cost on a "per host" basis, in the following
  46. format:
  47.  
  48. XStat.data file header:
  49. -----------------------
  50. H XSTAT DATA
  51.  
  52. This header must be the first line of XStat.data
  53.  
  54. XStat.data comment line:
  55. ------------------------
  56.  
  57. # any comments you wish to add to XStat.data
  58.  
  59. You may add comment lines anywhere in your XStat.data file, except before
  60. the file header.
  61.  
  62. XStat.data currency sign info:
  63. ------------------------------
  64. S <currency sign>
  65.  
  66. Tells XStat the currency sign for your country. This line must come before
  67. the first "N"-line. There can be only one "S"-line in your XStat.data file.
  68.  
  69. Examples:
  70.  
  71. # currency sign for the U.S.A.
  72. S $
  73.  
  74. # currency sign for Germany
  75. S DM
  76.  
  77. XStat.data host name info:
  78. --------------------------
  79. N <host name>
  80.  
  81. Starts a new connection cost data record. Must be followed by at least
  82. one "C"-line. <host name> should be the name of a host you're directly
  83. connected to, without any path or domain information.
  84.  
  85. Examples:
  86.  
  87. # my own newsfeed
  88. N imart
  89.  
  90. # my alternate newsfeed
  91. N cbmger
  92.  
  93. XStat.data connection time/cost info:
  94. -------------------------------------
  95. C <start time> <duration> <price>
  96.  
  97. Tells XStat that between <start time> and <start time of next C-line>
  98. a connection will cost <price> per <duration>. "C"-lines must follow
  99. a "N"-line. <duration> must be in seconds, <price> in the currency of
  100. your choice.
  101.  
  102. The first "C"-line must be for "SU-00:00:00"!
  103.  
  104. Example:
  105. N imart
  106. C SU-00:00:00 120 0.23
  107. C MO-08:00:00  60 0.23
  108. C MO-18:00:00 120 0.23
  109.  
  110. From Sunday 0:00:00 to Monday 7:59:59, a connection between my
  111. site and my newsfeed "imart" will cost 0.23DM/120sec.
  112.  
  113. Between Monday 8:00:00 and Monday 17:59:59, a connection between my site
  114. and my newsfeed "imart" will cost 0.23DM/60sec.
  115.  
  116. With this short example, the connection cost for the rest of the
  117. week (from Monday 18:00:00 to Saturday 23:59:59) would be 0.23DM/120sec.
  118.  
  119. Full length example for XStat.data:
  120. -----------------------------------
  121.  
  122. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  123. H XSTAT DATA
  124. #==============================================================================
  125. # XStat connection cost data file
  126. #==============================================================================
  127. #
  128. #------------------------------------------------------------------------------
  129. # currency sign for Germany; S must come before first N
  130. #------------------------------------------------------------------------------
  131. S DM
  132. #
  133. #------------------------------------------------------------------------------
  134. # my own newsfeed, connection cost is 0.23/60sec (0.23/120sec night & weekend)
  135. #------------------------------------------------------------------------------
  136. N imart
  137. C SU-00:00:00 120 0.23
  138. C MO-08:00:00  60 0.23
  139. C MO-18:00:00 120 0.23
  140. C TU-08:00:00  60 0.23
  141. C TU-18:00:00 120 0.23
  142. C WE-08:00:00  60 0.23
  143. C WE-18:00:00 120 0.23
  144. C TH-08:00:00  60 0.23
  145. C TH-18:00:00 120 0.23
  146. C FR-08:00:00  60 0.23
  147. C FR-18:00:00 120 0.23
  148. #
  149. #------------------------------------------------------------------------------
  150. # cbmger, connection cost is 0.23/21sec (0.23/42sec night & weekend)
  151. #------------------------------------------------------------------------------
  152. N cbmger
  153. C SU-00:00:00  42 0.23
  154. C MO-08:00:00  21 0.23
  155. C MO-18:00:00  42 0.23
  156. C TU-08:00:00  21 0.23
  157. C TU-18:00:00  42 0.23
  158. C WE-08:00:00  21 0.23
  159. C WE-18:00:00  42 0.23
  160. C TH-08:00:00  21 0.23
  161. C TH-18:00:00  42 0.23
  162. C FR-08:00:00  21 0.23
  163. C FR-18:00:00  42 0.23
  164. #
  165. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  166.  
  167.  
  168.  
  169. Usage
  170. =====
  171. XStat [?] [DATA name] [FILE name] [V | VERBOSE] [FD | FROMDATE date]
  172.           [TD | TODATE date] [NI | NOINCOM] [NO | NOOUTGO]
  173.           [H | HOSTNAME name] [M | MONTH shortdate]
  174.  
  175. You may also use the environment variable "XSTATARGS" to specify
  176. parameters. This is very useful if you're using XStat from the
  177. Workbench (XStat doesn't really support Workbench, that's why
  178. there's no icon for it).
  179.  
  180. ?
  181. -
  182. Displays a help message.
  183.  
  184. DATA name
  185. ---------
  186. Tells XStat to read its connection cost data from file <name>.
  187. <name> defaults to "UULIB:XStat.data".
  188.  
  189. FILE name
  190. ---------
  191. Tells XStat to extract the statistic information from file <name>.
  192. <name> defaults to "UUSPOOL:XferStat".
  193.  
  194. V | VERBOSE
  195. -----------
  196. Enables the "verbose" mode. When on, XStat displays short statistics
  197. for every connect found in the Xferstat file. Defaults to "off".
  198. Specify VERBOSE to turn verbose mode on.
  199.  
  200. FD | FROMDATE date
  201. ------------------
  202. Tells XStat to ignore connects before <date>. <date> defaults to "01-JAN-78".
  203. You may use any valid AmigaDOS date string, including things like
  204. "TODAY" or "YESTERDAY". XStat will add a time string of "00:00:00" internally,
  205. you may not do this yourself. Be careful, if you're using Workbench 2.1 (which
  206. is [ought to be] currently available to registered developers only) you'll have
  207. to use your locale date specifications, for example "HEUTE" instead of "TODAY"
  208. if you're using the german locale.
  209.  
  210. TD | TODATE date
  211. ----------------
  212. Tells XStat to ignore connects after <date>. <date> defaults to current
  213. date/time. You may use any valid AmigaDOS date string, including things
  214. like "TODAY" or "YESTERDAY" (with the same 2.1/locale limitations as FD).
  215. XStat will add a time string of "23:59:59" internally, you may not do this
  216. yourself.
  217.  
  218. M | MONTH shortdate
  219. -------------------
  220. Tells XStat to ignore FD and TD, and to compute the statistics for the
  221. specified month instead. The month must be given in the format "MMM-YY",
  222. without specifying the day. Example: "MONTH JUN-92" will compute the stats
  223. for June 92. MONTH is inactive as default.
  224.  
  225. NI | NOINCOM
  226. ------------
  227. Tells XStat to suppress evaluation of incoming calls; defaults to off.
  228. Specify "NI" to suppress evaluation of incoming calls. Meaning of this
  229. switch was inverted before version 1.04.
  230.  
  231. NO | NOOUTGO
  232. ------------
  233. Tells XStat to suppress evaluation of outgoing calls; defaults to off.
  234. Specify "NO" to suppress evaluation of outgoing calls. Meaning of this
  235. switch was inverted before version 1.04.
  236.  
  237. Q | QUIET
  238. ---------
  239. Tells XStat to suppress non-fatal error messages; defaults to off.
  240. Specify QUIET to suppress non-fatal errors.
  241.  
  242. This is very handy for getting rid of those "(ignoring this one)" messages
  243. for failed connects.
  244.  
  245. H | HOSTNAME
  246. ------------
  247. Tells XStat to evaluate calls to host <name> only; defaults to all hosts.
  248. Starting with V1.06, if <name> contains any valid AmigaDos pattern,
  249. XStat will display subtotals for each host that matches these patterns.
  250.  
  251. Patterns are not case sensitive.
  252.  
  253. Example: XStat hostname (a|x)#?
  254.          will evaluate calls to all hosts that start with an "a" or "x",
  255.          and will display sub-totals for each of those hosts.
  256.  
  257.  
  258.  
  259. XStat's output
  260. ==============
  261.  
  262. Example:
  263.  
  264. > XStat V1.07
  265. > © Copyright 1992 by Jürgen Weinelt
  266. > XStat is Freeware - read the docs for details.
  267. >
  268. >
  269. >
  270. >
  271. > Connection statistics for incoming calls:
  272. > -----------------------------------------
  273. >
  274. > no connects recorded.
  275. >
  276. >
  277. >
  278. > Connection statistics for outgoing calls:
  279. > -----------------------------------------
  280. >
  281. > connects              53
  282. > online time        35421 sec      (     668 sec/connect)
  283. > units                323 units    (   6.094 units/connect)
  284. > cost               74.29 DM       (   1.402 DM/connect)
  285. >
  286. > brutto read      7493483 bytes    (  141386 bytes/connect)
  287. > brutto send       882109 bytes    (   16643 bytes/connect)
  288. > netto read       6526244 bytes    (  123136 bytes/connect)
  289. > netto send        132519 bytes    (    2500 bytes/connect)
  290. >
  291. > ø brutto speed       236 cps      (     243 cps peak)
  292. > ø netto speed        187 cps      (     200 cps peak)
  293. > ø brutto cost      9.301 DM/MB
  294. > ø netto cost      11.699 DM/MB
  295.  
  296. connects
  297. --------
  298. Number of connects.
  299.  
  300. online time
  301. -----------
  302. Total online time, and average online time per connect.
  303.  
  304. units
  305. -----
  306. Phone units consumed, and average phone units consumed per connect.
  307.  
  308. Note: in Germany, a "phone unit" is an indivisible time quantum
  309. (sounds like quantum physics :-). This means even if your connect
  310. is shorter than that, the phone company still charges for the entire
  311. time quantum. Example: unit duration is 60 seconds, connect time was
  312. 97 seconds, phone company charges two units (120 seconds).
  313.  
  314. You can influence the unit duration by editing the XStat.data file;
  315. the <duration> in the "C"-lines tells XStat the unit duration.
  316.  
  317. cost
  318. ----
  319. Total cost, and average cost per connect.
  320.  
  321. brutto read
  322. -----------
  323. Total bytes read (including protocol information), and average (per connect).
  324.  
  325. brutto send
  326. -----------
  327. Total bytes sent (including protocol information), and average (per connect).
  328.  
  329. netto read
  330. ----------
  331. Total bytes read (excluding protocol information), and average (per connect).
  332.  
  333. netto send
  334. ----------
  335. Total bytes sent (excluding protocol information), and average (per connect).
  336.  
  337. ø brutto speed
  338. --------------
  339. Average transmission speed, including protocol overhead, and speed of
  340. fastest connect.
  341.  
  342. ø netto speed
  343. -------------
  344. Average transmission speed, excluding protocol overhead, and speed of
  345. fastest connect.
  346.  
  347. ø brutto cost
  348. -------------
  349. Average cost per MByte, including protocol overhead.
  350.  
  351. ø netto cost
  352. ------------
  353. Average cost per MByte, excluding protocol overhead.
  354.  
  355.  
  356.  
  357. History
  358. =======
  359. V1.07   list of connection statistics was not sorted correctly. Fixed.
  360. V1.06   extended "hostname" to include pattern matching and "per host" feature
  361. V1.05   added "per host" statistics
  362. V1.04   fixed a bug (problem with locale), switched to dos.library "ReadArgs()"
  363. V1.03   added monthly statistics.
  364. V1.02   added peak brutto/netto cps rating.
  365. V1.01   XStat used to guru when brutto or netto xfer was 0 bytes. Fixed.
  366. V1.00   initial release.
  367.  
  368. V0.9x   several test/beta versions, limited circulation
  369.  
  370.  
  371.  
  372. Known problems/bugs
  373. ===================
  374. None so far...
  375.  
  376. Well, actually, there's one problem I can't do anything about... the
  377. online time is not very accurate. That's because the connection start
  378. time seems to state the time the modem says "CONNECT", not the real
  379. start time of the (phone line) connection.
  380.  
  381.  
  382.  
  383. You can contact me through the Usenet:
  384.  
  385.    uunet.uu.net!cbmvax!cbmehq!cbmger!imart!hcast!jow
  386.  
  387. (Sorry, still no domain address)
  388.  
  389. Or through the snail mail:
  390.  
  391.    Jürgen Weinelt
  392.    Zur Kanzel 1
  393.    D-8783 Hammelburg
  394.    Germany
  395.  
  396. You might also try posting to comp.sys.amiga.programmer or alt.sys.amiga.uucp,
  397. I'll probably read those newsgroups.
  398.